By way of Introduction

Liberty Basic introduced the ability to pass variables into functions and sub programs by reference when version four was released. Prior to that, variables were only passed by value.

What does it mean?

I have seen quite a few people get tripped up by these concepts.

When a variable is passed by value it is COPIED and the copy is passed on to the called routine. This leaves the original intact for the main program to use later.

It is like this image of the coin. The original is left in the main program, while a copy is passed into the called routine.

When a variable is passed by reference the original variable is literally removed from main program and given to the called routine. If the variable is altered by the called routine it will be altered for the main program when the called routine terminates.

It is like this image of the coin. The original no longer remains in the main program. It is only in the called routine.

Why use one or the other?

The default method of passing variables in Liberty Basic is by value. This is the way all variables should be passed into called routines. This provides safety for the original variable. It can not be changed by the called routine.

If you desire to return a SINGLE value from a called routine you should use a FUNCTION, returning the desired value. Typically you would not want to pass a single variable back and forth by reference.

Passing variables by reference is a very handy feature when you need to pass two or more variables into or out of a function. This is where the ability to pass by reference really shines. Consider a sub program that converts a single RGB color value into its composite Red, Green and Blue values:

sub GetColors color, red, green, blue
    blue=int(color/(256*256))
    green=int((color-blue*256*256)/256)
    red=color-blue*256*256-green*256
end sub

This is a great little sub program, but if you call it you will not get any results out of it. Now you could get around this problem by declaring red, green and blue as GLOBAL, but that has its own set of problems. For one, what if those variables are used somewhere else for another purpose? Also consider code reuse - what will happen if you try to reuse this sub program but forget it requires global variables to be defined?

This is where our friend the ByRef comes into play. By causing the variables red, green and blue to be passed in by reference we can then pass the new values back out.

sub GetColors color, byref red, byref green, byref blue
    blue=int(color/(256*256))
    green=int((color-blue*256*256)/256)
    red=color-blue*256*256-green*256
end sub

This sub program is fully self-contained. It does not require any additional setup, global variables or arrays to pass values back and forth. It is capable of returning three values from the call. There is a caveat to using the sub program though. You must understand that if you are passing in variables they will be changed by the called routine.

Here is the code in use in a very simple program:

color = 828504
call GetColors color, red, green, blue
print color, red, green, blue
end

sub GetColors color, byref red, byref green, byref blue
    blue=int(color/(256*256))
    green=int((color-blue*256*256)/256)
    red=color-blue*256*256-green*256
end sub

Remember - ByRef, useful if you need to pass two or more values out of a called routine. Under normal circumstances it is always best to pass your variables by value!